home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 22
/
Cream of the Crop 22.iso
/
program
/
pcl4c60.zip
/
PCL4CREF.DOC
< prev
next >
Wrap
Text File
|
1996-10-24
|
60KB
|
1,562 lines
Personal Communications Library
For the C Language
(PCL4C)
REFERENCE MANUAL
Version 6.0
October 21, 1996
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 1995
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Voice : 205-881-4630
FAX : 205|880|0925
BBS : 205-880-9748
email : info@marshallsoft.com
Anon FTP : ftp.marshallsoft.com /marshallsoft
web : www.marshallsoft.com
_______
____|__ | (R)
--+ | +-------------------
| ____|__ | Association of
| | |_| Shareware
|__| o | Professionals
--+--+ | +---------------------
|___|___| MEMBER
PCL4C Reference Manual Page 1
C O N T E N T S
Chapter Page
Table of Contents.............................2
Introduction..................................3
SioBaud....................................4
SioBrkKey..................................4
SioBrkSig..................................5
SioCTS.....................................5
SioDCD.....................................6
SioDelay...................................6
SioDone....................................7
SioDSR.....................................7
SioDTR.....................................8
SioError...................................8
SioFIFO....................................9
SioFlow....................................9
SioGetc...................................10
SioGetDiv.................................10
SioGets...................................11
SioInfo...................................11
SioIRQ....................................12
SioLine...................................12
SioLoopBack...............................13
SioModem..................................13
SioParms..................................14
SioPorts..................................14
SioPutc...................................15
SioPuts...................................15
SioRead...................................16
SioReset..................................16
SioRI.....................................17
SioRTS....................................17
SioRxBuf..................................18
SioRxClear................................18
SioRxQue..................................19
SioStats..................................19
SioTimer..................................20
SioTxBuf..................................20
SioTxClear................................21
SioTxFlush................................21
SioTxQue..................................22
SioUART...................................22
SioUnGetc.................................23
Function Summary.............................24
Error Code Summary...........................25
Code Examples................................26
PCL4C Reference Manual Page 2
Introduction
This manual lists all of the PCL4C functions in alphabetical order.
Every library function will return a value as follows:
1. Negative values for error conditions. See last page of this
manual for a list of error values and their meanings.
2. Non-negative values when returning data (eg: SioLine).
3. Zero otherwise.
When debugging an application, be sure to test all return values.
Use SioError to print the associated text for errors.
Example Code Segment
+---------------------------------------------------------------+
| int Code; /* MUST be 'int', not 'char' */ |
| |
| Code = SioFunction( ); /* any PCL4C function */ |
| if(Code<0) |
| {/* error returned */ |
| SioError(Code); /* SioError prints error text */ |
| SioDone(Port); /* always call SioDone last */ |
| exit(1); |
| } |
| /* no errors */ |
| ...your application code... |
| |
+---------------------------------------------------------------+
For more examples, examine each of the example programs provided
(MINIMAL.C, SIMPLE.C, LOGIN.C, DOOR.C, SPAWN.C, SELFTEST.C, etc.) in
the distribution archive. 32-bit users should examine SIMPLE32.C and
SELF32.C.
You may also wish to examine the TERM.C example program in the
protocol library (PPL4C).
Refer to the User's Manual (PCL4C.USR) for additional information.
Also examine the PCL4C.H include file in which library constants are
defined. 32-bit users should refer to PCL4C32.H.
Note that there are a few differences between the 16-bit & 32-bit
libraries:
(1) SioRxBuf & SioTxBuf: 32-bit users should pass 0 as the Selector.
(2) SioStats is available only in 32-bit library.
(3) SioLoopBack & SioBrkKey are not available in 32-bit library.
Lastly, note that the shareware versions of all our libraries are
limited to 4 ports (COM1 through COM4), but that the registered
version can use 20 ports (COM1 through COM20).
PCL4C Reference Manual Page 3
+-------------+-----------------------------------------------------+
| SioBaud | Sets the baud rate of the selected port. |
+-------------+-----------------------------------------------------+
Syntax int SioBaud(int Port,int BaudCode)
/* Port: Port selected (COM1 - COM16) */
/* BaudCode: Baud code */
Remark The SioBaud function sets the baud rate without resetting the
port. It is used to change the baud rate after calling
SioReset.
Code Rate Name Code Rate Name
0 300 Baud300 5 9600 Baud9600
1 600 Baud600 6 19200 Baud19200
2 1200 Baud1200 7 38400 Baud38400
3 2400 Baud2400 8 57600 Baud57600
4 4800 Baud4800 9 115200 Baud115200
Return -4 : No such port. Expect 0 to MaxPort.
-11 : Bad baud rate code. See above code values.
Other SioReset
+-------------+-------------+---------------------------+-----------+
| SioBrkKey | Returns non|0 if ^BREAK was pressed [16|bit only] |
+-------------+-------------+---------------------------+-----------+
Syntax int SioBrkKey(void)
Remark The SioBrkKey function returns a TRUE value (non-zero) if the
Control-BREAK key was pressed, else it returns a zero. Use
SioBrkKey as a safety exit from a polling loop. [16-bit lib
only].
Return -1 : Control-BREAK was pressed.
0 : Control-BREAK was NOT pressed.
Other SioBrkSig
PCL4C Reference Manual Page 4
+-------------+-----------------------------------------------------+
| SioBrkSig | Asserts, cancels, or detects BREAK signal. |
+-------------+-----------------------------------------------------+
Syntax int SioBrkSig(int Port,char Cmd)
/* Port: Port selected (COM1 thru COM20) */
/* Cmd: ASSERT ('A'), CANCEL ('C'), or DETECT ('D')*/
Remark The SioBrkSig function controls the BREAK bit in the line
status register. The legal commands are:
ASSERT_BREAK ('A') : to assert BREAK
CANCEL_BREAK ('C') : to cancel BREAK
DETECT_BREAK ('D') : to detect BREAK
ASSERT_BREAK, CANCEL_BREAK, and DETECT_BREAK are defined in
PCL4C.H.
SioBreak is often used by one side to signal the other than an
error condition has occurred.
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
-6 : Illegal command. Expected 'A', 'C', or 'D'.
>0 : BREAK signal detected (DETECT command only)
Other SioBrkKey
+-------------+-----------------------------------------------------+
| SioCTS | Reads the Clear to Send (CTS) modem status bit. |
+-------------+-----------------------------------------------------+
Syntax int SioCTS(int Port)
/* Port: Port selected (COM1 thru COM20) */
Remark The SioCTS function is used to read the Clear to Send (CTS)
modem status bit.
The CTS line is used by some error correcting modems to
implement hardware flow control. CTS is dropped by the modem
to signal the computer not to send data and is raised to
signal the computer to continue.
See the User's Manual for a discussion of flow control.
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
0 : CTS is clear.
>0 : CTS is set.
Other SioFlow, SioDSR, SioRI, SioDCD, and SioModem.
PCL4C Reference Manual Page 5
+-------------+-----------------------------------------------------+
| SioDCD | Reads the Data Carrier Detect (DCD) modem staus bit|
+-------------+-----------------------------------------------------+
Syntax int SioDCD(int Port)
/* Port: Port selected (COM1 thru COM20) */
Remark The SioDCD function is used to read the Data Carrier Detect
(DCD) modem status bit. Also see SioModem.
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
0 : DCD is clear.
>0 : DCD is set.
Other SioDSR, SioCTS, SioRI, and SioModem.
+-------------+-----------------------------------------------------+
| SioDelay | Delays one or more timer tics. |
+-------------+-----------------------------------------------------+
Syntax int SioDelay(int Tics)
/* Tics: # timer tics to delay */
Remark The SioDelay function is used to delay one or more timer
tics, where each timer tic is approximately 55 milliseconds
(18.2 tics to the second). Be carefull calling SioDelay since
it will not return until the specified delay has occurred.
Return zero.
Other SioTimer
PCL4C Reference Manual Page 6
+-------------+-----------------------------------------------------+
| SioDone | Terminates further serial processing. | *
+-------------+-----------------------------------------------------+
Syntax int SioDone(int Port)
/* Port: Port selected (COM1 thru COM20) */
Remark The SioDone function terminates further serial processing.
SioDone MUST be called before exiting your application so that
interrupts can be restored to their original state. Failure to
do this can crash the operating system. If you forget to call
SioDone before exiting, be sure to re-boot your computer. You
can call SioDone even if SioReset has not been called, so it
is good practice to always call SioDone before exiting your
application.
Also note that SioDone de-references the transmit and receive
buffers set up by SioRxBuf and SioTxBuf. However, it does NOT
free the transmit and receive buffers. It is good practice to
free the transmit and receive buffers (after calling SioDone)
if they were allocated by malloc (or fmalloc).
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
Other SioReset.
+-------------+-----------------------------------------------------+
| SioDSR | Reads the Data Set Ready (DSR) modem status bit. | *
+-------------+-----------------------------------------------------+
Syntax int SioDSR(int Port)
/* Port: Port selected (COM1 thru COM20) */
Remark The SioDSR function is used to read the Data Set Ready (DSR)
modem status bit. The DSR line is typically used by the serial
device (such as a modem) to indicate that it is connected.
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
0 : DSR is clear.
>0 : DSR is set
Other SioCTS, SioRI, SioDCD, and SioModem
PCL4C Reference Manual Page 7
+-------------+-----------------------------------------------------+
| SioDTR | Set, clear, or read Data Terminal Ready (DTR) bit.|
+-------------+-----------------------------------------------------+
Syntax int SioDTR(int Port,char Cmd)
/* Port: Port selected (COM1 thru COM20) */
/* Cmd: DTR command (SET, CLEAR, or READ) */
Remark The SioDTR function controls the Data Terminal Ready (DTR) bit
in the modem control register. The DTR line is typically used
by your program to tell the serial device that you are
connected. DTR should always be set when communicating with a
modem. Commands (defined in PCL4C.H) are:
SET_LINE ('S') : to set DTR (ON)
CLEAR_LINE ('C') : to clear DTR (OFF)
READ_LINE ('R') : to read DTR
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
-5 : Not one of 'S', 'C', or 'R'.
0 : DTR is OFF (READ_LINE Command).
>0 : DTR is ON (READ_LINE Command).
Other SioRTS.
+-------------+-----------------------------------------------------+
| SioError | Displays error in text. |
+-------------+-----------------------------------------------------+
Syntax int SioError(int Code)
/* Code: PCL4C error code */
Remark The SioError function displays the error in text corresponding
to the error code returned from a PCL4C function. During
development of a communications application, it is a good idea
to always test return codes, and print out their descriptions
with SioError [the 32-bit lib uses file SioError.c].
Return zero.
PCL4C Reference Manual Page 8
+-------------+-----------------------------------------------------+
| SioFIFO | Sets the FIFO trigger level (16550 UART only). |
+-------------+-----------------------------------------------------+
Syntax int SioFIFO(int Port,int LevelCode)
/* Port: Port selected (COM1 thru COM20) */
/* LevelCode: FIFO level code (see below) */
Remark The SioFIFO function is used to enable both transmit and
receive FIFOs for 16550 UARTS, and to set the trigger level at
which receive interrupts are generated.
For example, if the FIFO level is set to 8, then the 16550
UART will not generate an interrupt until 8 bytes have been
received. This reduces the number of interrupts generated and
allows faster processing with slower machines or when running
simultaneous ports.
To test for a 16550 UART, call SioFIFO with a LevelCode of
other than FIFO_OFF. SioFIFO can be called for the 8250 and
16450 UART without ill effect.
Level code: FIFO_OFF, LEVEL_1, LEVEL_4, LEVEL_8, LEVEL_14.
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
>0 : FIFO level set.
0 : FIFO level not set (not 16550).
+------------+------------------------------------------------------+
| SioFlow | Sets hardware (RTS/CTS) flow control. |
+------------+------------------------------------------------------+
Syntax int SioFlow(int Port,int Tics)
/* Port: Port selected (COM1 thru COM20) */
/* Tics: # tics before timeout */
Remark The SioFlow function is used to enable or disable hardware
flow control. Hardware flow control uses RTS and CTS to
control data flow between the modem and the computer. Refer to
the User's Manual for a discussion of flow control. To enable
hardware flow control, call SioFlow with Flag >= 0.
"Tics" is the number of timer tics (18.2 per second) before a
call to SioPutc or SioPuts will time out because CTS was not
set.
Flow control is disabled after resetting a port. To
explicitly disable hardware flow control, call SioFlow with
Tics=-1.
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
=0 : Flow control disabled.
>0 : Flow control enabled.
Other SioPutc and SioPuts
PCL4C Reference Manual Page 9
+------------+------------------------------------------------------+
| SioGetc | Reads the next character from the serial line. |
+------------+------------------------------------------------------+
Syntax int SioGetc(int Port,int Tics)
/* Port: Port selected (COM1 thru COM20) */
/* Tics: Timeout */
Remark The SioGetc function reads a byte from the selected serial
port. The function will wait for the number of system tics
given by the 'Tics' argument before returning 'timed out'.
There are 18.2 tics to the second.
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
-1 : If timed out.
>0 : Character read.
Other SioUnGetc and SioPutc.
+---------------+---------------------------------------------------+
| SioGetDiv | Reads the baud rate divisor. |
+---------------+---------------------------------------------------+
Syntax int SioGetDiv(int Port)
/* Port: Port selected (COM1 thru COM20) */
Remark The SioGetDiv function reads the baud rate divisor. The baud
rate can then be determined from the divisor by using the
following table:
Baud Divisor Baud Divisor Baud Divisor
300 0180 4800 0018 38400 0003
1200 0060 9600 000C 57600 0002
2400 0030 19200 0006 115200 0001
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
>0 : Baud rate divisor.
Other SioParms.
PCL4C Reference Manual Page 10
+------------+------------------------------------------------------+
| SioGets | Receive a buffer from the serial line. |
+------------+------------------------------------------------------+
Syntax int SioGets(int Port,char *Buffer,int Length)
/* Port: Port selected (COM1 thru COM20) */
/* Buffer: Character buffer */
/* Length: Length of Buffer (# of requested bytes) */
Remark The SioGets function reads bytes from the selected serial
port. This function will read either the number of requested
bytes or read fewer if no character is immediately available.
SioGets cannot return more characters than are in the receive
buffer at the time it is called. The number of characters
actually read is returned.
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
-1 : If timed out.
>0 : Number of characters read into Buffer.
Other SioUnGetc and SioGetc.
+-------------+-----------------------------------------------------+
| SioInfo | Return PCL4C library information. |
+-------------+-----------------------------------------------------+
Syntax int SioInfo(char Cmd)
/* Cmd: Command (see below) */
Remark The SioInfo function returns a word value depending on the
character argument in the table below. This function is
usefull for understanding what the hardware is doing. Note
that the command argument is case sensitive. The 32-bit lib
only returns the version number. See SioStats for 32-bit info.
Info Codes
'V' : Version [as hex byte XY means version X.Y]
'I' : TRUE if library compiled with TX interrupts enabled.
'M' : Memory model (0=small,1=compact,2=medium,3=large)
'P' : TRUE if compiled for protected mode.
'T' : Total (over all ports) transmitter interrupts.
'R' : Total (over all ports) receiver interrupts.
'd' : Total (over all ports) times RTS dropped.
'r' : Total (over all ports) times RTS raised.
'c' : Total (over all ports) times CTS drop detected.
Return -1 : Function argument not recognized.
>=0 : Value as per above table.
Other SioStats
PCL4C Reference Manual Page 11
+-------------+-----------------------------------------------------+
| SioIRQ | Assigns an IRQ line to a port. |
+-------------+-----------------------------------------------------+
Syntax int SioIRQ(int Port,intIRQcode)
/* Port: Port selected (COM1 thru COM20) */
/* IRQcode: IRQ number [IRQ2..IRQ15] */
Remark The SioIRQ function assigns an IRQ line to a po7rt. That is,
SioIRQ maps an IRQ to a port. SioIRQ (like SioUART) must be
called before calling SioReset. Unless you have a non-standard
(COM1 & COM3 use IRQ4 while COM2 & COM4 use IRQ3) serial port
configuration (or don't want to run more than 2 ports
concurrently), you will not need to call SioIRQ. You should be
EXTREMELY careful with SioIRQ as it can lock your machine up
if given incorrect information.
In particular, remember that your port hardware must generate
the interrupt that you have specified. You should refer to
your serial board hardware manual for specfic instructions in
configuring your hardware. Be sure to call SioPorts first to
setup DigiBoard ports if you have them. Refer to the PCL4C
Users Manual for additional information.
Return -4 : No such port. Expect 0 to MaxPort.
15 : Port already enabled. SioReset has already been called.
-17 : No such IRQ.
-18 : ISR limit (maximum of 4 PC IRQs) exceeded.
0 : Otherwise
Other SioUART and SioPorts.
+-------------+-----------------------------------------------------+
| SioLine | Reads the line status register. |
+-------------+-----------------------------------------------------+
Syntax int SioLine(int Port)
/* Port: Port selected (COM1 thru COM20) */
Remark The SioLine function reads the line status register. The
individual bit masks are as follows:
0x40 = Transmitter empty.
0x20 = Transmitter buffer empty.
0x10 = Break detected.
0x08 = Framming error.
0x04 = Parity error.
0x02 = Overrun error.
0x01 = Data ready.
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
>0 : Line status (rightmost byte of word).
Other SioModem.
PCL4C Reference Manual Page 12
+-------------+--------------------------------+--------------------+
| SioLoopBack | Does a UART loopback test. [16|bit lib only] |
+-------------+--------------------------------+--------------------+
Syntax int SioLoopBack(int Port)
/* Port: Port selected (COM1 thru COM20) */
Remark SioLoopBack makes use of the built in loopback test capability
of the INS8250 family UART. Normally SioLoopBack will never
need to be called unless you suspect that your UART is bad.
Many UARTs must be reset after running a loopback test.
Return 0 : Loopback test is successfull.
-2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
-12 : Loopback test fails.
+-------------+------------------------------------------------------+
| SioModem | Reads the modem status register. |
+-------------+------------------------------------------------------+
Syntax int SioModem(int Port, int Mask)
/* Port: Port selected (COM1 thru COM20) */
/* Mask: Modem function mask */
Remark The SioModem function reads the modem register. The bit
definitions for the function mask are as follows:
Bit Name Function Bit Name Function
7 DCD Data Carrier Detect 3 DeltaDCD DCD has changed
6 RI Ring Indicator 2 DeltaRI RI has changed
5 DSR Data Set Ready 1 DeltaDSR DSR has changed
4 CTS Clear To Send 0 DeltaCTS CTS has changed
Bits 4 through 7 represent the absolute state of their
respective RS-232 inputs. Bits 0 through 3 represent a change
in the state of their respective RS-232 inputs since last
read. Once UART register 3 is read, the Delta bits are
cleared. Thus, it is best not to depend on the Delta bits.
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
>0 : Modem status (rightmost byte of word).
Other SioCTS, SioDCD, SioDSR and SioRI.
PCL4C Reference Manual Page 13
+-------------+-----------------------------------------------------+
| SioParms | Sets parity, stop bits, and word length. |
+-------------+-----------------------------------------------------+
Syntax int SioParms(int Port,int Parity,int StopBits,int DataBits)
/* Port: Port selected (COM1 - COM16) */
/* Parity: Parity code [0,1,2] */
/* StopBits: Stop bits code [0,1] */
/* DataBits: Word length code [0,1,2,3] */
Remark The SioParms function sets the parity, stop bits, and data
length. If the default parity (none), stop bits (1), or word
length (8) is not acceptable, then they can be changed by
calling SioParms. SioParms can be called either before or
after calling SioReset. See file PCL4C.H.
Parity codes: NoParity, OddParioty, EvenParity.
StopBits codes: OneStopBit, TwoStopBits.
DataBits codes: WordLength7, WordLength8.
Return -4 : No such port. Expect 0 to MaxPort.
-7 : Bad parity code selected. Expecting 0 to 2.
|8 : Bad stop bits code. Expecting 0 or 1.
-9 : Bad word length code. Expecting 0 to 3.
Other SioReset.
+-------------+-----------------------------------------------------+
| SioPorts | Sets number of PC & Digiboard / BOCA Board ports. |
+-------------+-----------------------------------------------------+
Syntax int SioPorts(int Ports,int FirstPort,int Status,int Code)
/* Ports: Total number of ports */
/* FirstPort: First DigiBoard or BOCA port */
/* Status: DigiBoard Status Register */
/* Code: PC_PORTS, DIGIBOARD, or BOCABOARD */
Remark The SioPorts function must be called before ANY other serial
functions. The purpose of the SioPorts function is to set the
total number of ports, the first DigiBoard (or BOCA board)
port and the DigiBoard (or BOCA board) status register
address.
Once SioPorts is called, all COM ports starting with
"FirstPort" will be treated as DigiBoard (or BOCA board)
ports. The default setup is 4 standard PC ports and no
DigiBoard or BOCA ports [ SioPorts(4,4,0,PC_PORTS) ].
Refer to ther PCL4C users manual for more information on the
DigiBoard and BOCA board. Many other multiport boards are
functionally equivalent to either the DigiBoard or the BOCA
board.
Return -4 : No such port. Expect 0 to 9.
0 : No error (sets MaxPort to NumberPorts-1).
Other SioUART, SioIRQ, and Code Examples.
PCL4C Reference Manual Page 14
+-------------+-----------------------------------------------------+
| SioPutc | Transmit a character over a serial line. |
+-------------+-----------------------------------------------------+
Syntax int SioPutc(int Port,char Ch)
/* Port: Port selected (COM1 thru COM20) */
/* Ch: Character to send */
Remark The SioPutc function transmits one character. If flow control
has been enabled, then SioPutc may return a -1 (time out) if
the number of tics specified in the SioFlow function was
exceeded waiting for the modem to raise CTS.
If transmitter interrupts are enabled, SioPutc returns a -1 if
the transmit buffer is already full. Otherewise the byte is
placed in the transmit buffer, awaiting transmission by the
PCL4C interrupt service routine. If transmitter interrupts are
not enabled, the byte is loaded directly into the UART
transmit buffer.
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
-1 : Timed out waiting for CTS (flow control enabled), or
transmit buffer already full.
Other SioPuts, SioFlow, and SioTxFlush.
+-------------+-----------------------------------------------------+
| SioPuts | Transmit a buffer over a serial line. |
+-------------+-----------------------------------------------------+
Syntax int SioPuts(int Port,char *Buffer,int Length)
/* Port: Port selected (COM1 thru COM20) */
/* Buffer: Character buffer */
/* Length: Length of Buffer */
Remark The SioPuts function transmits each buffer character over the
selected serial line. The number of characters actually
transmitted is returned. This function can take a long time
for large buffers if transmitter interrupts are not enabled!
If flow control has been enabled, then SioPuts may transmit
fewer characters than requested if the number of tics
specified in the SioFlow function was exceeded waiting for the
modem to raise CTS.
If transmitter interrupts are enabled, SioPuts will transmit
fewer than the number of characters requested if the transmit
buffer would overflow. The actual number of characters
transmitted is returned.
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
>=0: Number of characters actually transmitted.
Other SioPutc, SioFlow, and SioTxFlush.
PCL4C Reference Manual Page 15
+-------------+-----------------------------------------------------+
| SioRead | Reads any UART register. |
+-------------+-----------------------------------------------------+
Syntax int SioRead(int Port,int Reg)
/* Port: Port selected (COM1 thru COM20) */
/* Reg: UART register (0 to 7) */
Remark The SioReset function directly reads the contents of any of
the 7 UART registers. This function is useful when debugging
application programs and as a method for verifying UART
contents.
The line status register (register 5) can also be read with
SioLine while the modem status register (register 6) can also
be read with SioModem.
Return -3 : No buffer available. Call SioRxBuf first.
-4 : No such port. Expect 0 to MaxPort.
Other SioLine and SioModem.
+-------------+------------------------------------------------------+
| SioReset | Initialize a serial port for processing. |
+-------------+------------------------------------------------------+
Syntax int SioReset(int Port,int BaudCode)
/* Port: Port selected (COM1 thru COM20) */
/* BaudCode: Baud code or -1 */
Remark The SioReset function initializes the selected serial port.
SioReset should be called after calling SioParm and SioRxBuf
but before making any other calls to PCL4C. SioReset uses the
parity, stop bits, and word length value previously set if
SioParm was called, otherwise the default values (see SioParm)
are used.
Recall that COM1 and COM3 share the same interrupt vector and
therefore cannot operate simultaneously. Similiarly, COM2 and
COM4 cannot operate simultaneously. Any other combination of
two ports can be used.
By specifing NORESET (-1) for the baud rate code, the port
will NOT be reset. This is used to "take over" a port from a
host communications program that allows a "DOS gateway".
External protocols can be implemented this way.
Return -3 : No buffer available. Call SioRxBuf first.
-4 : No such port. Expect 0 to MaxPort.
-11 : Bad baud rate code selected. Expecting 0 to 9.
|13 : UART undefined. SioUART(Port,0) was called.
|14 : Bad or missing UART. Hardware may not be present.
|15 : Port already enabled. SioReset was already called.
-16 : Interrupt already in use.
>=0 : Port has been reset. Return value is line status.
Other SioBaud, SioParms, SioRxBuf, SioTxBuf, SioDone & SioUART.
PCL4C Reference Manual Page 16
+-------------+-----------------------------------------------------+
| SioRI | Reads the Ring Indicator (RI) modem status. |
+-------------+-----------------------------------------------------+
Syntax int SioRI(int Port)
/* Port: Port selected (COM1 thru COM20) */
Remark The SioRI function is used to read the Ring Indicator (RI)
modem status bit. Also see SioModem.
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
0 : RI is clear.
>0 : RI is set (RING has occurred).
Other SioDSR, SioCTS, SioDCD, and SioModem.
+-------------+-----------------------------------------------------+
| SioRTS | Sets, clears, or reads Request to Send (RTS) line. |
+-------------+-----------------------------------------------------+
Syntax int SioRTS(Port, char Cmd)
/* Port: Port selected (COM1 thru COM20) */
/* Cmd: RTS command (SET, CLEAR, or READ) */
Remark The SioRTS function controls the Request to Send (RTS bit
in the modem control register.
The RTS line is used by most error correcting modems to
implement hardware flow control. RTS is dropped by the
computer to signal the modem not to send data, and is raised
to signal the modem to continue. RTS should be set when
communicating with a modem unless Flow Control is being used.
Refer to the User's Manual for a discussion of flow control.
Commands (defined in PCL4C.H) are:
SET_LINE ('S') : set RTS (ON)
CLEAR_LINE ('C') : clear RTS (OFF)
READ_LINE ('R') : read RTS
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
-5 : Command is not one of 'S', 'C', or 'R'.
0 : RTS is OFF (READ_LINE Command).
>0 : RTS is ON (READ_LINE Command).
Other SioFlow and SioDTR.
PCL4C Reference Manual Page 17
+------------+------------------------------------------------------+
| SioRxBuf | Sets up receive buffers. |
+------------+------------------------------------------------------+
Syntax int SioRxBuf(int Port,int Selector,SizeCode)
/* Port: Port selected (COM1 thru COM20) */
/* Selector: Receive buffer segment [selector for PM] */
/* SizeCode: Buffer size code */
Remark The SioRxBuf function passes the address segment and size of
the receive buffer to PCL4C. Recall that PCL4C requires a
receive buffer for each port in simultaneous operation since
the receive function is interrupt driven. It must be called
before any incoming characters can be received. SioRxBuf must
be called before SioReset. Buffer size codes are listed in
"PCL4C.H". [Pass 0 for Selector in 32-bit programs].
Size Code Buffer Size PCL4C.H Name
4 128 bytes Size128
5 256 bytes Size256
6 512 bytes Size512
7 1024 bytes Size1024 or Size1K
8 2048 bytes Size2048 or Size2K
9 4096 bytes Size4096 or Size4K
10 8192 bytes Size8192 or Size8K
11 16384 bytes Size16384 or Size16K
12 32768 bytes Size32768 or Size32K
Return -4 : No such port. Expect 0 to MaxPort.
-10 : Bad buffer size code. Expecting 0 to 11.
Other SioReset, SioTxBuf and Code Examples.
+------------+------------------------------------------------------+
| SioRxClear | Cleares (clears) the receive buffer. |
+------------+------------------------------------------------------+
Syntax int SioRxClear(int Port)
/* Port: Port selected (COM1 thru COM20) */
Remark The SioRxClear function will delete any characters in the
receive buffer for the specified port. After execution, the
receive buffer will be empty. Call SioRxBuf after resetting a
port in order to delete any spurious characters.
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
Other SioRxQue.
PCL4C Reference Manual Page 18
+-------------+-----------------------------------------------------+
| SioRxQue | Returns the number of bytes in the receive queue. |
+-------------+-----------------------------------------------------+
Syntax int SioRxQue(int Port)
/* Port: Port selected (COM1 thru COM20) */
Remark The SioRxQue function will return the number of characters in
the receive queue at the time of the call. It can be used to
implement XON/XOFF flow control.
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
Other SioRxClear.
+-----------+--------------------------------------+----------------+
| SioStats | Return PCL4C library information (32|bit ONLY) |
+-----------+--------------------------------------+----------------+
Syntax int SioStats(Port,Cmd)
/* Port: Port selected (COM1 thru COM20) */
/* Cmd: Command (see below) */
Remark The SioStats function returns a word value depending on the
character argument in the table below. This function is
usefull for understanding what the hardware is doing. Note
that the command argument is case sensitive.
Info Codes
'T' : Total transmitter interrupts.
'R' : Total receiver interrupts.
'K' : # bytes kickstarted.
'C' : # bytes transmitted.
'd' : Total times RTS dropped.
'r' : Total times RTS raised.
'c' : Total times CTS drop detected.
Return -1 : Function argument not recognized.
>=0 : Value as per above table.
Other SioInfo
PCL4C Reference Manual Page 19
+------------+------------------------------------------------------+
| SioTimer | Returns the number of system clock tics. |
+------------+------------------------------------------------------+
Syntax long SioTimer(void)
Remark The SioTimer function will return the number of system clock
tics since midnight, at 18.2065 tics per second. This function
is usefull for timing various functions.
Other SioDelay
+------------+------------------------------------------------------+
| SioTxBuf | Sets up transmitter buffer. |
+------------+------------------------------------------------------+
Syntax int SioTxBuf(int Port,int Selector,int SizeCode)
/* Port: Port selected (COM1 thru COM20) */
/* Selector: Receive buffer segment [selector in PM] */
/* SizeCode: Buffer size code */
Remark The SioTxBuf function passes the address segment and size of
the transmit buffer to PCL4C, provided that you will link with
a PCL4C library with transmitter interrupts enabled. [Pass 0
for Selector in 32-bit programs]. SioTxBuf() must be called
before SioReset.
Size Code Buffer Size PCL4C.H Name
4 128 bytes Size128
5 256 bytes Size256
6 512 bytes Size512
7 1024 bytes Size1024 or Size1K
8 2048 bytes Size2048 or Size2K
9 4096 bytes Size4096 or Size4K
10 8192 bytes Size8192 or Size8K
11 16384 bytes Size16384 or Size16K
12 32768 bytes Size32768 or Size32K
Return -4 : No such port. Expect 0 to MaxPort.
-10 : Bad buffer size code. Expecting 0 to 11.
Other SioRxBuf, SioReset and Code Examples.
PCL4C Reference Manual Page 20
+------------+------------------------------------------------------+
| SioTxClear | Cleares (clears) the transmitter buffer. |
+------------+------------------------------------------------------+
Syntax int SioTxClear(int Port)
/* Port: Port selected (COM1 thru COM20) */
Remark The SioTxClear function will delete any characters in the
transmit buffer for the specified port, provided that you will
link with a PCL4C library with transmitter interrupts enabled.
After execution, the transmit buffer will be empty.
Once this function is called, any character in the transmit
buffer (put there by SioPutc) will be lost and therefore not
transmitted. This function is not used unless the transmitter
interrupts are enabled Refer to the PCL4C Users Manual for
information on transmitter (TX) interrupts.
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
Other SioTxFlush and SioTxQue.
+------------+------------------------------------------------------+
| SioTxFlush | Flushes the transmitter buffer. |
+------------+------------------------------------------------------+
Syntax int SioTxFlush(int Port)
/* Port: Port selected (COM1 thru COM20) */
Remark The SioTxFlush function will re-enable transmitter interrupts
if they had been disabled by CTS dropping. This has the effect
of forcing all data out of the transmitter queue unless
stopped again by CTS going down.
Once the transmitter interrupt has been disabled (by CTS going
down), then the only way to restart it is by calling one of
the serial I/O functions (SioPutc, SioPuts, SioGetc, or
SioGets), SioTxQue, or SioTxFlush.
The primary purpose of SioTxFlush is to provide an explicit
means of restarting transmitter interrupts.
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
Other SioTxQue.
PCL4C Reference Manual Page 21
+------------+------------------------------------------------------+
| SioTxQue | Returns the number of bytes in the transmit queue. |
+------------+------------------------------------------------------+
Syntax int SioTxQue(int Port)
/* Port: Port selected (COM1 thru COM20) */
Remark The SioTxQue function will return the number of characters in
the transmit queue at the time of the call, provided that you
will link with a PCL4C library with transmitter interrupts
enabled.
This function is not used unless the transmitter interrupts
are enabled. Refer to the PCL4C Users Manual for information
on transmitter (TX) interrupts.
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
Other SioTxFlush.
+------------+------------------------------------------------------+
| SioUART | Sets the UART base address. |
+------------+------------------------------------------------------+
Syntax int SioUART(int Port,int Address)
/* Port: Port selected (COM1 thru COM20) */ int Port; /* COM1 to COM4 */
/* Address: UART address */
Remark The SioUART function sets the UART base address for the
specified port. SioUART must be called before SioReset in
order to have effect. Be extremely sure that you know what
you are doing! Note that PCL4C uses the standard PC/XT/AT
port addresses, interrupt request lines, and interrupt service
vectors. Therefore, this function is only needed for
non-standard ports.
Return >0 : The previous base address for this port.
-4 : No such port. Expect 0 to MaxPort.
-15 : Port already enabled. SioReset has already been called.
Other SioPorts, SioIRQ, and SioReset.
PCL4C Reference Manual Page 22
+------------+-----+------------------------------------------------+
| SioUnGetc | "Un|gets" the last character read with SioGetc(). |
+------------+-----+------------------------------------------------+
Syntax int SioUnGetc(int Port,char Ch)
/* Port: Port selected (COM1 thru COM20) */
/* Ch: Character to unget */
Remark The SioUnGetc function returns ("pushes") the character back
into the serial input buffer. The character pushed will be
the next character returned by SioGetc. Only one character
can be pushed back (except for 32-bit libs). This function
works just like the "ungetc" function in the C language.
Return -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
Other SioReset.
PCL4C Reference Manual Page 23
Function Summary
+-------------+----------+----------+----------+----------+
| Function | Arg1 | Arg2 | Arg3 | Arg4 |
+-------------+----------+----------+----------+----------+
| SioBaud | Port | BaudCode | | |
| SioBrkKey | | | | |
| SioBrkSig | Port | Cmd | | |
| SioCTS | Port | | | |
| SioDCD | Port | | | |
| SioDelay | Tics | | | |
| SioDone | Port | | | |
| SioDSR | Port | | | |
| SioDTR | Port | Cmd | | |
| SioError | Code | | | |
| SioFIFO | Port | LevelCode| | |
| SioFlow | Port | Tics | | |
| SioGetc | Port | Tics | | |
| SioGetDiv | Port | | | |
| SioGets | Port | Buffer | Length | |
| SioInfo | Cmd | | | |
| SioIRQ | Port | IRQcode | | |
| SioLine | Port | | | |
| SioLoopBack | Port | | | |
| SioModem | Port | Mask | | |
| SioParms | Port | Parity | StopBits | DataBits |
| SioPorts | NbrPorts | FirstPort| StatusReg| Code |
| SioPutc | Port | Ch | | |
| SioPuts | Port | Buffer | Length | |
| SioRead | Port | Reg | | |
| SioReset | Port | BaudCode | | |
| SioRI | Port | | | |
| SioRTS | Port | Cmd | | |
| SioRxBuf | Port | Segment | SizeCode | |
| SioRxClear | Port | | | |
| SioRxQue | Port | | | |
| SioStats | Port | Cmd | | |
| SioTimer | | | | |
| SioTxBuf | Port | Segment | SizeCode | |
| SioTxClear | Port | | | |
| SioTxFlush | Port | | | |
| SioTxQue | Port | | | |
| SioUART | Port | Address | | |
| SioUnGetc | Port | Ch | | |
+-------------+----------+----------+----------+----------+
PCL4C Reference Manual Page 24
Error Code Summary
+------+--------------------------------------------------------+
| Code | Description |
+------+--------------------------------------------------------+
| 0 | No error. |
| -1 | Timeout waiting for I/O. |
| |2 | Port not enabled. Call SioReset first. |
| |3 | No buffer available. Call SioRxBuf first. |
| |4 | No such port. Expect 0 to MaxPort. (COM1 = 0) |
| |5 | Expected 'S', 'C', or 'R' as 2nd argument. |
| |6 | Expected 'A', 'C', or 'D' as 2nd argument. |
| |7 | Bad parity code specified. Expected 0 to 7. |
| |8 | Bad stop bits code specified. Expected 0 or 1. |
| -9 | Bad wordlength code specified. Expect 0 to MaxPort. |
| -10 | Bad buffer size code specified. Expected 0 to 11. |
| |11 | Bad baud rate code. Expected 0 to 9. |
| |12 | Loopback test fails. |
| |13 | UART undefined. |
| |14 | Missing or bad UART. (no UART hardware ?) |
| |15 | Port already enabled. |
| |16 | ISR (interrupt) already in use. |
| |17 | No such IRQ. (Should be 2 to 7) |
| |18 | ISR limit (maximum of 4 PC IRQs) exceeded. |
| |19 | Shareware screen cannot be displayed. |
| |20 | 5-minute runtime expired (32-bit lib ONLY). |
+-+----+---+--------------------------+-------------------------+
PCL4C Reference Manual Page 25
Code Examples
SioRxBuf / SioTxBuf Example
int BufSize = 1024;
int SizeCode = Size1024;
char far *Ptr;
int BufSeg;
...
/* allocate receive buffer + 16 bytes */
Ptr = (char far *) _fmalloc(BufSize+16);
BufSeg = FP_SEG(Ptr) + ((FP_OFF(Ptr)+15)>>4);
/* pass receive buffer segment to PCL4C */
SioRxBuf(Port,BufSeg,SizeCode);
/* allocate transmit buffer + 16 bytes */
Ptr = (char far *) _fmalloc(BufSize+16);
BufSeg = FP_SEG(Ptr) + ((FP_OFF(Ptr)+15)>>4);
/* pass transmit buffer segment to PCL4C */
SioTxBuf(Port,BufSeg,SizeCode)
DigiBoard Example
/* use 0x140 for odd IRQs & 0x141 for even IRQs */
SioPorts(8,COM1,0x140,DIGIBOARD);
for(i=COM1;i<=COM8;i++)
{/* set DigiBoard UART addresses */
SioUART(i,0x100+8*i);
/* set DigiBoard for IRQ5 */
SioIRQ(i,IRQ5);
}
BOCA Board Example
/* use base port + 7 */
SioPorts(16,COM1,0x100+7,BOCABOARD);
for(i=COM1;i<=COM16;i++)
{/* set BOCA Board UART addresses */
SioUART(i,0x100+8*i);
/* set DigiBoard for IRQ5 */
SioIRQ(i,IRQ5);
}
PCL4C Reference Manual Page 26
